home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 443_01 / doc / info / cncl.info-4 < prev    next >
Encoding:
GNU Info File  |  1996-01-04  |  46.2 KB  |  1,672 lines
  1. This is Info file cncl.info, produced by Makeinfo-1.63 from the input
  2. file cncl.texi.
  3.  
  4.    This file documents the use of CNCL, the Communication Networks Class
  5. Library.
  6.  
  7.    Copyright (C) 1993-1996, Communication Networks.
  8.  
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.  
  13.    Permission is granted to copy and distribute modified versions of
  14. this manual under the conditions for verbatim copying, provided that the
  15. entire resulting derived work is distributed under the terms of a
  16. permission notice identical to this one.
  17.  
  18.    Permission is granted to copy and distribute translations of this
  19. manual into other languages, under the above conditions for modified
  20. versions.
  21.  
  22. 
  23. File: cncl.info,  Node: CNSimTime,  Next: Event Example,  Prev: CNEventIterator,  Up: Events
  24.  
  25. CNSimTime -- Simulation Time
  26. ============================
  27.  
  28. SYNOPSIS
  29. --------
  30.  
  31.    `#include <CNCL/SimTime.h>'
  32.  
  33. TYPE
  34. ----
  35.  
  36.    `typedef double CNSimTime'
  37.  
  38. DESCRIPTION
  39. -----------
  40.  
  41.    `CNSimTime' is a double variable which keeps the current simulation
  42. time.
  43.  
  44. 
  45. File: cncl.info,  Node: Event Example,  Next: CNArray,  Prev: CNSimTime,  Up: Events
  46.  
  47. Example of an Event Driven Simulation
  48. =====================================
  49.  
  50.    The following example shows how to program an M/M/1 queuing system
  51. simulation with CNCL events:
  52.  
  53.      // -*- C++ -*-
  54.      
  55.      #include <iostream.h>
  56.      
  57.      #include <CNCL/QueueFIFO.h>
  58.      #include <CNCL/EventScheduler.h>
  59.      #include <CNCL/FiboG.h>
  60.      #include <CNCL/NegExp.h>
  61.      #include <CNCL/Moments.h>
  62.      #include <CNCL/Job.h>
  63.      
  64.      enum { NJOBS=100000 };
  65.      
  66.      enum { EV_JOB, EV_TIMER_G, EV_TIMER_S }; // Event types for M/M/1 simulation
  67.      
  68.      class Server : public CNEventHandler
  69.      {
  70.      private:
  71.          CNJob *job;             // Served job
  72.          CNQueueFIFO queue;    // CNQueue
  73.          CNRandom &rnd_b;      // Distribution of service time b
  74.          CNMoments t_w, t_b;   // Evaluation tau_w, tau_b
  75.          enum { ST_WAITING, ST_SERVING };
  76.      
  77.      public:
  78.          virtual void event_handler(const CNEvent *ev);
  79.      
  80.          void print_results();
  81.          void eval_job(CNJob *job);
  82.      
  83.          Server(CNRandom &rnd) : rnd_b(rnd), job(NIL), t_w("tau_w"), t_b("tau_b")
  84.          {
  85.              state(ST_WAITING);
  86.          }
  87.      };
  88.      
  89.      class Generator : public CNEventHandler
  90.      {
  91.      private:
  92.          CNRandom &rnd_a;      // Distribution of arrival time a
  93.          Server *server;       // Connected queue/server
  94.          long n;
  95.      
  96.      public:
  97.          virtual void event_handler(const CNEvent *ev);
  98.      
  99.          Generator(CNRandom &rnd,Server *serv) : rnd_a(rnd),server(serv),n(0) {}
  100.      };
  101.      
  102.      void Generator::event_handler(const CNEvent *ev)
  103.      {
  104.          if(n == NJOBS)
  105.              // Stop simulation
  106.              return;
  107.      
  108.          // Incoming event -> generate new Job
  109.          send_now(new CNEvent(EV_JOB, server, new CNJob));
  110.          // Random delay
  111.          send_delay(new CNEvent(EV_TIMER_G), rnd_a());
  112.          n++;
  113.      }
  114.      
  115.      
  116.      
  117.      void Server::event_handler(const CNEvent *ev)
  118.      {
  119.          switch(state())
  120.          {
  121.          case ST_SERVING:
  122.              switch(ev->type())
  123.              {
  124.              case EV_JOB:
  125.                  // Incoming job, put into queue
  126.                  {
  127.                      CNJob *job;
  128.                      job = (CNJob *)ev->object();
  129.                      job->in = now();
  130.                      queue.put(job);
  131.                  }
  132.                  break;
  133.      
  134.              case EV_TIMER_S:
  135.                  // Timer event, service time run down
  136.                  job->out = now();
  137.                  // Evaluate job
  138.                  eval_job(job);
  139.                  delete job;
  140.                  job = NIL;
  141.                  // Get new job from queue
  142.                  if(!queue.empty())
  143.                  {
  144.                      job = (CNJob *)queue.get();
  145.                      job->start = now();
  146.                      // Random service time
  147.                      send_delay(new CNEvent(EV_TIMER_S), rnd_b());
  148.                      state(ST_SERVING);
  149.                  }
  150.                  else
  151.                      state(ST_WAITING);
  152.                  break;
  153.              }
  154.              break;
  155.      
  156.          case ST_WAITING:
  157.              switch(ev->type())
  158.              {
  159.              case EV_JOB:
  160.                  // Incoming job
  161.                  job = (CNJob *)ev->object();
  162.                  job->in    = now();
  163.                  job->start = now();
  164.                  // CNRandom service time
  165.                  send_delay(new CNEvent(EV_TIMER_S), rnd_b());
  166.                  state(ST_SERVING);
  167.                  break;
  168.              }
  169.              break;
  170.          }
  171.      }
  172.      
  173.      void Server::eval_job(CNJob *job)
  174.      {
  175.          t_w.put(job->start - job->in);
  176.          t_b.put(job->out   - job->in);
  177.      }
  178.      
  179.      
  180.      void Server::print_results()
  181.      {
  182.          cout << t_w << t_b;
  183.      }
  184.      
  185.      main()
  186.      {
  187.          CNRNG   *rng   = new CNFiboG;
  188.          CNNegExp rnd_a(10, rng);
  189.          CNNegExp rnd_b( 5, rng);
  190.      
  191.          Server           server(rnd_b);
  192.          Generator        generator(rnd_a, &server);
  193.      
  194.          CNEventScheduler scheduler;
  195.          scheduler.start(new CNEvent(EV_TIMER_G, &generator));
  196.      
  197.          server.print_results();
  198.      
  199.      }
  200.  
  201. 
  202. File: cncl.info,  Node: Arrays,  Next: Object Management,  Prev: Events,  Up: Top
  203.  
  204. Array Classes
  205. *************
  206.  
  207.    The class `CNArray' and the derived classes provide arrays of
  208. different data types with array range checking.  `CNArrayObject'
  209. manages pointers to `CNObject'. The other classes `CNArray'<type>
  210. manage arrays of standard data types.
  211.  
  212.    The main purpose of these classes is to provide arrays with range
  213. checking, i.e. access to an array element outside the arrays bounds
  214. will terminate the program.
  215.  
  216.    Range checking may be disabled by defining the preprocessor macro
  217. `NO_RANGE_CHECK', e.g. by supplying `-DNO_RANGE_CHECK' on the
  218. compiler's command line.
  219.  
  220. * Menu:
  221.  
  222. CNArray Classes
  223. ---------------
  224. * CNArray::        Abstract Array Base Class
  225. * CNArrayObject::    Array of Pointer to CNObject
  226. * CNArrayInt::        Array of Integer
  227. * Other CNArray<type>::    Arrays of Other <Type>s
  228. * CNArray2::            Base class for 2-dimensional arrays
  229. * CNArray2Char::        char array class
  230. * Other CNArray2<type>::Other array classes
  231.  
  232. 
  233. File: cncl.info,  Node: CNArray,  Next: CNArrayObject,  Prev: Event Example,  Up: Arrays
  234.  
  235. CNArray -- Abstract Array Base Class
  236. ====================================
  237.  
  238. SYNOPSIS
  239. --------
  240.  
  241.    `#include <CNCL/Array.h>'
  242.  
  243. TYPE
  244. ----
  245.  
  246.    `CN_ARRAY'
  247.  
  248. * Menu:
  249.  
  250. BASE CLASSES
  251. ------------
  252. * CNObject::        Root of the CNCL Hierarchy
  253.  
  254. DERIVED CLASSES
  255. ---------------
  256. * CNArrayObject::    Array of Pointer to CNObject
  257. * CNArrayInt::        Array of Int
  258. * Other CNArray<type>::    Arrays of Other <Type>s
  259.  
  260. RELATED CLASSES
  261. ---------------
  262.  
  263. DESCRIPTION
  264. -----------
  265.  
  266.    `CNArray' is the base class of the `CNArray'<type> classes. It
  267. defines the common interface.
  268.  
  269.    Constructors:
  270.  
  271. `CNArray();'
  272. `CNArray(size_t xsize);'
  273.      Initializes `CNArray'.
  274.  
  275.    In addition to the member functions required by CNCL, `CNArray'
  276. provides:
  277.  
  278. `size_t get_size() const;'
  279. `size_t size() const;'
  280.      Returns the size of the array.
  281.  
  282. `void set_size(size_t sz = 0 );'
  283. `virtual void size(size_t sz=0) = 0;'
  284.      Sets the size of the array. The `size'-function must be implemented
  285.      in the derived classes.
  286.  
  287. 
  288. File: cncl.info,  Node: CNArrayObject,  Next: CNArrayInt,  Prev: CNArray,  Up: Arrays
  289.  
  290. CNArrayObject -- Array of Pointer to CNObject
  291. =============================================
  292.  
  293. SYNOPSIS
  294. --------
  295.  
  296.    `#include <CNCL/ArrayObject.h>'
  297.  
  298. TYPE
  299. ----
  300.  
  301.    `CN_ARRAYOBJECT'
  302.  
  303. * Menu:
  304.  
  305. BASE CLASSES
  306. ------------
  307. * CNArray::        Abstract Array Base Class
  308.  
  309. DERIVED CLASSES
  310. ---------------
  311.  
  312. RELATED CLASSES
  313. ---------------
  314. * CNArrayInt::        Array of Int
  315. * Other CNArray<type>::    Arrays of Other <Type>s
  316.  
  317. DESCRIPTION
  318. -----------
  319.  
  320.    `CNArrayObject' manages arrays of pointers to `CNObject'.
  321.  
  322.    Constructors:
  323.  
  324. `CNArrayObject();'
  325. `CNArrayObject(Param *param);'
  326. `CNArrayObject(size_t sz, CNObjPtr def=0);'
  327.      Initializes the array and optionally sets array size to `sz'. All
  328.      element pointers are initialized to `NIL' or to `def'.
  329.  
  330. `CNArrayObject(const CNArrayObject &a);'
  331.      Copy constructor.
  332.  
  333.    Destructors:
  334.  
  335. `~CNArrayObject();'
  336.      Deletes the array. The referenced objects are NOT deleted!
  337.  
  338.    In addition to the member functions required by CNCL, `CNArrayObject'
  339. provides:
  340.  
  341. `typedef CNObject *CNObjPtr;'
  342. `virtual void size(size_t sz = 0 );'
  343.      Sets the size of the array.
  344.  
  345. `void put (int index, CNObjPtr value);'
  346.      Puts value into array at indexed location.
  347.  
  348. `CNObjPtr get (int index) const;'
  349.      Returns value of array at indexed location.
  350.  
  351. `CNObjPtr& operator[] (int index);'
  352.      Access to array by `operator []'.
  353.  
  354. `CNArrayObject &operator= (const CNArrayObject &a);'
  355.      Defines the `operator =' for the array to allow copying of arrays.
  356.  
  357. 
  358. File: cncl.info,  Node: CNArrayInt,  Next: Other CNArray<type>,  Prev: CNArrayObject,  Up: Arrays
  359.  
  360. CNArrayInt -- Array of Integer
  361. ==============================
  362.  
  363. SYNOPSIS
  364. --------
  365.  
  366.    `#include <CNCL/ArrayInt.h>'
  367.  
  368. TYPE
  369. ----
  370.  
  371.    `CN_ARRAYINT'
  372.  
  373. * Menu:
  374.  
  375. BASE CLASSES
  376. ------------
  377. * CNArray::        Abstract Array Base Class
  378.  
  379. DERIVED CLASSES
  380. ---------------
  381.  
  382. RELATED CLASSES
  383. ---------------
  384. * CNArrayObject::    Array of Pointer to CNObject
  385. * Other CNArray<type>::    Arrays of Other <Type>s
  386.  
  387. DESCRIPTION
  388. -----------
  389.  
  390.    `CNArrayInt' manages arrays of integer (the builtin type `int').
  391. `CNArrayInt' is presented here as an example for all `CNArray'<type>
  392. classes. The interface is the same for all classes only considering the
  393. different data types.
  394.  
  395.    Constructors:
  396.  
  397. `CNArrayInt();'
  398. `CNArrayInt(Param *param);'
  399. `CNArrayInt(size_t sz, int def=0);'
  400.      Initializes the array and optionally sets array size to `sz'. All
  401.      elements are set to the default value `def'.
  402.  
  403. `CNArrayInt(const CNArrayInt &a);'
  404.      Copy constructor.
  405.  
  406.    Destructors:
  407.  
  408. `~CNArrayInt();'
  409.      Deletes the array.
  410.  
  411.    In addition to the member functions required by CNCL, `CNArrayInt'
  412. provides:
  413.  
  414. `virtual void size(size_t sz = 0 );'
  415.      Sets the size of the array.
  416.  
  417. `void put (int index, int value);'
  418.      Puts value into array at indexed location.
  419.  
  420. `int get (int index) const;'
  421.      Returns value of array at indexed location.
  422.  
  423. `int& operator[] (int index);'
  424.      Access to array by `operator []'.
  425.  
  426. `CNArrayInt &operator= (const CNArrayInt &a);'
  427.      Defines the `operator =' for the array to allow copying of arrays.
  428.  
  429. 
  430. File: cncl.info,  Node: Other CNArray<type>,  Next: CNArray2,  Prev: CNArrayInt,  Up: Arrays
  431.  
  432. CNArray<type> -- Arrays of Other <Type>s
  433. ========================================
  434.  
  435. DESCRIPTION
  436. -----------
  437.  
  438.    CNCL currently provides array classes for the data types `char',
  439. `double', `float', `int', `long', and `CNObject *' with the classes
  440. `CNArrayChar', `CNArrayDouble', `CNArrayFloat', `CNArrayInt',
  441. `CNArrayLong', and `CNArrayObject' respectively.
  442.  
  443.    All CNCL compatible objects can be stored in a `CNArrayObject', thus
  444. that there is no need for specialized array types.
  445.  
  446.    Nevertheless it is possible to generate arrays of other data types
  447. with the `CNarray' script.
  448.  
  449.    Usage:
  450.  
  451.      `CNarray' name
  452.  
  453.    The required parameter is the name of the data type. `CNarray'
  454. generates two files ArrayName.h and ArrayName.c with the definition and
  455. implementation of the desired array class.
  456.  
  457.    Please note that name must be a single word, pointers and references
  458. are not allowed, either. If you need an array of pointers or e.g. an
  459. array of `unsigned long', you can use an appropiate typedef:
  460.  
  461.      typedef unsigned long ulong;
  462.      typedef Data *DataP;
  463.  
  464.    and then generate an array
  465.  
  466.      CNarray ulong
  467.      CNarray DataP
  468.  
  469.    yielding the classes `CNArrayUlong' and `CNArrayDataP'.
  470.  
  471. 
  472. File: cncl.info,  Node: CNArray2,  Next: CNArray2Char,  Prev: Other CNArray<type>,  Up: Arrays
  473.  
  474. CNArray2  -- Base class for 2-dimensional arrays
  475. ================================================
  476.  
  477. SYNOPSIS
  478. --------
  479.  
  480.    `#include <CNCL/Array2.h >'
  481.  
  482. TYPE
  483. ----
  484.  
  485.    `CN_ARRAY2'
  486.  
  487. * Menu:
  488.  
  489. BASE CLASSES
  490. ------------
  491. * CNObject::    Root of the CNCL Hierarchy
  492.  
  493. DERIVED CLASSES
  494. ---------------
  495. * CNArray2Char::     char array class
  496. * Other CNArray2<type>:: Other array classes
  497.  
  498. RELATED CLASSES
  499. ---------------
  500. * CNArray::    Abstract array base class
  501.  
  502. DESCRIPTION
  503. -----------
  504.  
  505.    `CNArray2' is the base class of the `CNArray2'<type> classes. It
  506. defines the common interface.
  507.  
  508.    Constructors:
  509.  
  510. `CNArray2();'
  511. `CNArray2(Param *param);'
  512. `CNArray2(size_t r, size_t c);'
  513.      Initializes `CNArray2'.The number of rows is r, the number of cols
  514.      c.
  515.  
  516.    In addition to the member functions required by CNCL, `CNArray2'
  517. provides:
  518.  
  519. `size_t get_rows() const;'
  520. `size_t rows() const;'
  521. `size_t get_cols() const;'
  522. `size_t cols() const;'
  523.      Returns the number of rows resp. cols.
  524.  
  525. `virtual void size(size_t r, size_t c) = 0;'
  526. `void set_size(size_t r, size_t c);'
  527.      Resizes the array.
  528.  
  529. 
  530. File: cncl.info,  Node: CNArray2Char,  Next: Other CNArray2<type>,  Prev: CNArray2,  Up: Arrays
  531.  
  532. CNArray2Char -- char array class
  533. ================================
  534.  
  535. SYNOPSIS
  536. --------
  537.  
  538.    `#include <CNCL/Array2Char.h>'
  539.  
  540. TYPE
  541. ----
  542.  
  543.    `CN_ARRAY2CHAR'
  544.  
  545. * Menu:
  546.  
  547. BASE CLASSES
  548. ------------
  549. * CNArray2::            Base class for 2-dimensional arrays
  550.  
  551.  
  552. DERIVED CLASSES
  553. ---------------
  554.  
  555. RELATED CLASSES
  556. ---------------
  557. * CNArray2::            Base class for 2-dimensional arrays
  558. * Other CNArray2<type>::Other array classes
  559.  
  560. DESCRIPTION
  561. -----------
  562.  
  563.    Constructors:
  564.  
  565. `CNArray2Char();'
  566. `CNArray2Char(CNParam *param);'
  567. `CNArray2Char(size_t r, size_t c, char def = 0);'
  568.      Initializes the `CNArray2Char' and optionally sets the arraysize to
  569.      r rows and c cols.
  570.  
  571. `CNArray2Char(const CNArray2Char &a);'
  572.      Copy constructor.
  573.  
  574.    Destructor:
  575.  
  576. `~CNArray2Char();'
  577.      Deletes the array.
  578.  
  579.    In addition to the member functions required by CNCL, `CNArray2Char'
  580. provides:
  581.  
  582. `virtual void size(size_t r, size_t c);'
  583.      Resizes the array to r rows and c cols.
  584.  
  585. `void put(int r, int c, chr value);'
  586.      Writes the character value to position (r, c).
  587.  
  588. `char get(int r, int c) const;'
  589.      Returns the character written on position (r, c).
  590.  
  591. `CNArrayChar& operator[] (int index);'
  592.      Access to array by `operator []'. The row `index' is returned.
  593.  
  594. `CNArray2Char &operator= (const CNArray2Char &a);'
  595.      Defines the `operator =' for the array to allow copying of arrays.
  596.  
  597. 
  598. File: cncl.info,  Node: Other CNArray2<type>,  Next: CNKey,  Prev: CNArray2Char,  Up: Arrays
  599.  
  600. CNArray2<type> -- 2 dimensional Arrays of Other <Type>s
  601. =======================================================
  602.  
  603. DESCRIPTION
  604. -----------
  605.  
  606.    CNCL currently provides 2 dimensional array classes for the data
  607. types `char', `double', `float', `int', `long', and `CNObject *' with
  608. the classes `CNArray2Char', `CNArray2Double', `CNArray2Float',
  609. `CNArray2Int', `CNArray2Long', and `CNArray2Object' respectively. The
  610. description of those classes is similar to `CNArray2Char'.
  611.  
  612.    All CNCL compatible objects can be stored in a `CNArray2Object', thus
  613. that there is no need for specialized array types.
  614.  
  615.    Nevertheless it is possible to generate arrays of other data types
  616. with the `CNarray2' script.
  617.  
  618.    Usage:
  619.  
  620.      `CNarray2' name
  621.  
  622.    The required parameter is the name of the data type. `CNarray2'
  623. generates two files Array2Name.h and Array2Name.c with the definition
  624. and implementation of the desired array class.
  625.  
  626.    Please note that name must be a single word, pointers and references
  627. are not allowed, either. If you need an array of pointers or e.g. an
  628. array of `unsigned long', you can use an appropiate typedef:
  629.  
  630.      typedef unsigned long ulong;
  631.      typedef Data *DataP;
  632.  
  633.    and then generate an array
  634.  
  635.      CNarray2 ulong
  636.      CNarray2 DataP
  637.  
  638.    yielding the classes `CNArray2Ulong' and `CNArray2DataP'.
  639.  
  640. 
  641. File: cncl.info,  Node: Object Management,  Next: Unix,  Prev: Arrays,  Up: Top
  642.  
  643. Object Management
  644. *****************
  645.  
  646.    The classes described in this chapter provide facilities necessary
  647. for object management, as abstract keys, hash tables, and an object
  648. management fronend class.
  649.  
  650. * Menu:
  651.  
  652. Hash Tables and Object Management
  653. ---------------------------------
  654. * CNKey::            Abstract Base Class for Object Management via Keys
  655. * CNKeyString::         Object Management via String Keys
  656. * CNKeyInt::        Object Management via Integer Keys
  657. * CNHashTable::        Abstract Hash Table Class
  658. * CNHashStatic::    Hash Tables with Static Capacity
  659. * CNHashDynamic::    Hash Tables with Dynamic Capacity
  660. * CNHashIterator::      Sequential Iterator for Hash Tables
  661. * CNManager::            Object Management Frontend
  662.  
  663. 
  664. File: cncl.info,  Node: CNKey,  Next: CNKeyString,  Prev: Other CNArray2<type>,  Up: Object Management
  665.  
  666. CNKey -- Abstract Base Class for Object Management via Keys
  667. ===========================================================
  668.  
  669. SYNOPSIS
  670. --------
  671.  
  672.    `#include <CNCL/Key.h>'
  673.  
  674. TYPE
  675. ----
  676.  
  677.    `CN_KEY'
  678.  
  679. * Menu:
  680.  
  681. BASE CLASSES
  682. ------------
  683. * CNObject::        Root of the CNCL Hierarchy
  684.  
  685. DERIVED CLASSES
  686. ---------------
  687. * CNKeyString::        Object Management via String Keys
  688. * CNKeyInt::        Object Management via Integer Keys
  689.  
  690. RELATED CLASSES
  691. ---------------
  692. * CNHashTable::        Abstract Base Class for Hash Tables
  693. * CNHashStatic::    Hash Tables with Static Capacity
  694. * CNHashDynamic::    Hash Tables with Dynamic Capacity
  695. * CNHashIterator::      Sequential Iterator for Hash Tables
  696. * CNManager::        Object Management Frontend
  697.  
  698. DESCRIPTION
  699. -----------
  700.  
  701.    `CNKey' is an abstract class for managing CNCL compatible objects
  702. via keys. Refer to the desription of the classes derived from `CNKey'
  703. for further information. Objects of this type can be stored in and
  704. retrieved from hash tables.
  705.  
  706.    Constructors:
  707.  
  708. `CNKey(CNObject *obj = NIL);'
  709. `CNKey(CNParam *param);'
  710.      Initializes `CNKey'.
  711.  
  712.    In addition to the member functions required by CNCL, `CNKey'
  713. provides:
  714.  
  715. `void set_object(CNObject *obj);'
  716. `void set_object(CNObject &obj);'
  717.      Stores a CNCL compatible object into the key. Normally, an object
  718.      is stored in a key at creation time via the constructor.
  719.  
  720. `CNObject *get_object() const;'
  721.      Gets the object stored in the key. If an object is not available,
  722.      `NIL' is returned.
  723.  
  724.    The following virtual functions are to be defined by derived classes:
  725.  
  726. `virtual unsigned long hash( unsigned long capacity, int par = 0) const = 0;'
  727.      Function to evaluate the hash-table value.
  728.  
  729. `virtual bool compare(CNKey *k) const = 0;'
  730. `virtual bool compare(CNKey &k) const = 0;'
  731.      Function to compare two `CNKeys'.
  732.  
  733. 
  734. File: cncl.info,  Node: CNKeyString,  Next: CNKeyInt,  Prev: CNKey,  Up: Object Management
  735.  
  736. CNKeyString -- Object Management via String Keys
  737. ================================================
  738.  
  739. SYNOPSIS
  740. --------
  741.  
  742.    `#include <CNCL/KeyString.h>'
  743.  
  744. TYPE
  745. ----
  746.  
  747.    `CN_KEYSTRING'
  748.  
  749. * Menu:
  750.  
  751. BASE CLASSES
  752. ------------
  753. * CNKey::        Abstract Base Class for Object Management via Keys
  754.  
  755. DERIVED CLASSES
  756. ---------------
  757.  
  758. RELATED CLASSES
  759. ---------------
  760. * CNKeyInt::        Object Management via Integer Keys
  761. * CNHashTable::        Abstract Base Class for Hash Tables
  762. * CNHashStatic::    Hash Tables with Static Capacity
  763. * CNHashDynamic::    Hash Tables with Dynamic Capacity
  764. * CNHashIterator::      Sequential Iterator for Hash Tables
  765. * CNManager::        Object Management Frontend
  766.  
  767. DESCRIPTION
  768. -----------
  769.  
  770.    `CNKeyString' is a class for managing CNCL compatible objects via
  771. `CNString' keys. Objects of this type can be stored in and retrieved
  772. from hash tables.
  773.  
  774.    Constructors:
  775.  
  776. `CNKeyString(CNStringR key_string, CNObject *obj = NIL);'
  777. `CNKeyString(CNParam *param);'
  778.      Initializes `CNKeyString'. The supplied string key is used to
  779.      calculate the hash table position. Therefore, the string key must
  780.      be unique. Make sure, that the string key is valid during the
  781.      whole lifetime of the respective key. Otherwise operations on this
  782.      key are unpredictable.
  783.  
  784.    In addition to the member functions required by CNCL, `CNKeyString'
  785. provides:
  786.  
  787. `CNStringR get_key() const;'
  788.      Returns the string key. Unlike the object the string key cannot be
  789.      changed.
  790.  
  791. `virtual unsigned long hash( unsigned long capacity, int par = 0) const;'
  792.      Evaluates and returns the hash-table value. `par'  is reserved for
  793.      future use, any other value than zero will result in an fatal
  794.      error.
  795.  
  796. `virtual bool compare(CNKey *k) const;'
  797. `virtual bool compare(CNKey &k) const;'
  798.      Compares two `CNKeys'.
  799.  
  800. 
  801. File: cncl.info,  Node: CNKeyInt,  Next: CNHashTable,  Prev: CNKeyString,  Up: Object Management
  802.  
  803. CNKeyInt -- Object Management via Integer Keys
  804. ==============================================
  805.  
  806. SYNOPSIS
  807. --------
  808.  
  809.    `#include <CNCL/KeyInt.h>'
  810.  
  811. TYPE
  812. ----
  813.  
  814.    `CN_KEYINT'
  815.  
  816. * Menu:
  817.  
  818. BASE CLASSES
  819. ------------
  820. * CNKey::        Abstract Base Class for Object Management via Keys
  821.  
  822. DERIVED CLASSES
  823. ---------------
  824.  
  825. RELATED CLASSES
  826. ---------------
  827. * CNKeyString::        Object Management via String Keys
  828. * CNHashTable::        Abstract Base Class for Hash Tables
  829. * CNHashStatic::    Hash Tables with Static Capacity
  830. * CNHashDynamic::    Hash Tables with Dynamic Capacity
  831. * CNHashIterator::      Sequential Iterator for Hash Tables
  832. * CNManager::        Object Management Frontend
  833.  
  834. DESCRIPTION
  835. -----------
  836.  
  837.    `CNKeyInt' is a class for managing CNCL compatible objects via
  838. integer keys. Objects of this type can be stored in and retrieved from
  839. hash tables.
  840.  
  841.    Constructors:
  842.  
  843. `CNKeyInt(unsigned long key_int, CNObject *obj = NIL);'
  844. `CNKeyInt(CNParam *param);'
  845.      Initializes `CNKeyInt'. The supplied integer key is used to
  846.      calculate the hash table position. Therefore, the integer key must
  847.      be unique.
  848.  
  849.    In addition to the member functions required by CNCL, `CNKeyInt'
  850. provides:
  851.  
  852. `unsigned long get_key() const;'
  853.      Returns the integer key. Unlike the object the integer key cannot
  854.      be changed.
  855.  
  856. `virtual unsigned long hash( unsigned long capacity, int par = 0) const;'
  857.      Evaluates the hash-table value.
  858.  
  859. `virtual bool compare(CNKey *k) const;'
  860. `virtual bool compare(CNKey &k) const;'
  861.      Compares two `CNKeys'.
  862.  
  863. 
  864. File: cncl.info,  Node: CNHashTable,  Next: CNHashStatic,  Prev: CNKeyInt,  Up: Object Management
  865.  
  866. CNHashTable -- Abstract Base Class for Hash Tables
  867. ==================================================
  868.  
  869. SYNOPSIS
  870. --------
  871.  
  872.    `#include <CNCL/HashTable.h>'
  873.  
  874. TYPE
  875. ----
  876.  
  877.    `CN_HASHTABLE'
  878.  
  879. * Menu:
  880.  
  881. BASE CLASSES
  882. ------------
  883. * CNObject::        Root of the CNCL Hierarchy
  884.  
  885. DERIVED CLASSES
  886. ---------------
  887. * CNHashStatic::    Hash Tables with Static Capacity
  888. * CNHashDynamic::    Hash Tables with Dynamic Capacity
  889.  
  890.  
  891. RELATED CLASSES
  892. ---------------
  893. * CNKey::        Abstract Base Class for Object Management via Keys
  894. * CNKeyString::        Object Management via String Keys
  895. * CNKeyInt::        Object Management via Integer Keys
  896. * CNHashIterator::      Sequential Iterator for Hash Tables
  897. * CNManager::        Object Management Frontend
  898.  
  899. DESCRIPTION
  900. -----------
  901.  
  902.    `CNHashTable' is an abstract base class for storing and retrieving
  903. CNCL compatible objects.
  904.  
  905.    Constructors:
  906.  
  907. `CNHashTable();'
  908. `CNHashTable(CNParam *param);'
  909.      Initializes `CNHashTable'.
  910.  
  911.    `CNHashTable' defines the following structs and constants:
  912.  
  913. `const unsigned long DEFAULT_HASH_TABLE_CAPACITY = 101;'
  914.      The default capacity of a hash table. This value is used in
  915.      derived classes.
  916.  
  917. `struct HashEntry { CNKey *he_CNKey; unsigned long he_HashValue; };'
  918.      Defines a single entry of the hash table.
  919.  
  920.    `CNHashTable' provides the following virtual functions which have to
  921. be defined in derived classes:
  922.  
  923. `virtual void store_key(CNKey *k) = 0;'
  924. `virtual void store_key(CNKey &k) = 0;'
  925.      Stores a key into the actual hash table (derived from class
  926.      `HashTable'). The actual hash table is a homogenous table.
  927.      Therefore, only keys of the same type may be stored into one
  928.      table. If you nevertheless try to store keys of a different type
  929.      into one table, it might be detected by the methods `get_key()' and
  930.      `get_object()'. Refer to the description of the derived classes
  931.      for further information.
  932.  
  933. `virtual CNKey *get_key(CNKey *k) const = 0;'
  934. `virtual CNKey *get_key(CNKey &k) const = 0;'
  935.      Returns the key which matches the supplied key. If no matching key
  936.      was found, `NIL' is returned.
  937.  
  938. `virtual CNObject *get_object(CNKey *k) const = 0;'
  939. `virtual CNObject *get_object(CNKey &k) const = 0;'
  940.      Returns the object of the key which matches the supplied key. If no
  941.      matching key was found or if no object has been stored in the key,
  942.      `NIL' is returned.
  943.  
  944. `virtual bool reset() = 0;'
  945.      Deletes all entries of the actual hash table and resets it to its
  946.      initial state. This method does not free the memory allocated for
  947.      the keys stored in the hash table. If the hash table is already
  948.      empty, `FALSE' is returned, otherwise `TRUE'.
  949.  
  950. `virtual bool reset_absolutely() = 0;'
  951.      Deletes all entries of the actual hash table and resets it to its
  952.      initial state. This method does free the memory allocated for the
  953.      keys stored in the hash table. If the hash table is already empty,
  954.      `FALSE' is returned, otherwise `TRUE'.
  955.  
  956. `virtual bool delete_key(Key *k) = 0;'
  957. `virtual bool delete_key(CNKey &k);'
  958.      Deletes the key `k' from the actual hash table. This method does
  959.      not free the memory allocated for the key stored in the hash
  960.      table. If the supplied key does not match any in the table,
  961.      `FALSE' is returned, otherwise `TRUE'.
  962.  
  963. `virtual bool delete_key_absolutely(CNKey *k) = 0;'
  964. `virtual bool delete_key_absolutely(CNKey &k) = 0;'
  965.      Deletes the key `k' from the actual hash table. This method does
  966.      free the memory allocated for the keys stored in the hash table.
  967.      If the supplied key does not match any in the table, `FALSE' is
  968.      returned, otherwise `TRUE'.
  969.  
  970. `virtual bool is_full() const = 0;'
  971.      If the actual table's capacity is exhausted, `TRUE' is returned,
  972.      otherwise `FALSE'.
  973.  
  974. `virtual bool is_empty() const = 0;'
  975.      If the actual table is empty, `TRUE' is returned, otherwise
  976.      `FALSE'.
  977.  
  978. `virtual unsigned long get_num_entries() const = 0;'
  979.      Returns the number of entries of the actual table.
  980.  
  981. `virtual unsigned long get_capacity() const = 0;'
  982.      Returns the capacity of the current table.
  983.  
  984. 
  985. File: cncl.info,  Node: CNHashStatic,  Next: CNHashDynamic,  Prev: CNHashTable,  Up: Object Management
  986.  
  987. CNHashStatic -- Hash Tables with Static Capacity
  988. ================================================
  989.  
  990. SYNOPSIS
  991. --------
  992.  
  993.    `#include <CNCL/HashStatic.h>'
  994.  
  995. TYPE
  996. ----
  997.  
  998.    `CN_HASHSTATIC'
  999.  
  1000. * Menu:
  1001.  
  1002. BASE CLASSES
  1003. ------------
  1004. * CNHashTable::        Abstract Base Class for Hash Tables
  1005.  
  1006. DERIVED CLASSES
  1007. ---------------
  1008.  
  1009. RELATED CLASSES
  1010. ---------------
  1011. * CNHashDynamic::    Hash Tables with Dynamic Capacity
  1012. * CNHashIterator::      Sequential Iterator for Hash Tables
  1013. * CNKey::        Abstract Base Class for Object Management via Keys
  1014. * CNKeyString::        Object Management via String Keys
  1015. * CNKeyInt::        Object Management via Integer Keys
  1016.  
  1017. DESCRIPTION
  1018. -----------
  1019.  
  1020.    `CNHashStatic' is a class which provides a hash table with static
  1021. capacity for storing and retrieving CNCL compatible objects.
  1022.  
  1023.    Constructors:
  1024.  
  1025. `CNHashStatic(unsigned long cap = DEFAULT_HASH_TABLE_CAPACITY);'
  1026. `CNHashStatic(CNParam *param);'
  1027.      Initializes `CNHashStatic'. The hash table's capacity is set to
  1028.      the value passed to CNHashStatic. The capacity is static,
  1029.      therefore, you cannot change it during the lifetime of an instance
  1030.      of this class.
  1031.  
  1032.    Destructors:
  1033.  
  1034. `~CNHashStatic();'
  1035.      Frees all internally allocated resources.
  1036.  
  1037.    `CNHashStatic' provides the member functions required by CNCL and
  1038. `CNHashTable'.  Some member functions defined in `CNHashTable' and
  1039. implemented in `CNHashStatic' demand further explanation:
  1040.  
  1041. `void store_key(CNKey *k);'
  1042.      Stores a key into the homogenous hash table. Only keys of the same
  1043.      type may be stored into the same table. The methods `get_key()' and
  1044.      `get_object()' should detect it. If you try to store a key into an
  1045.      already full table, an error message is displayed and the program
  1046.      is terminated.
  1047.  
  1048. `bool delete_key(CNKey *k);'
  1049.      Deletes the key from the actual hash table which matches the given
  1050.      key. After having deleted a key from the hash table, the whole
  1051.      table is rehashed, i.e. the positions of all entries within the
  1052.      hash table are recalculated and all entries are stored in a new
  1053.      hash table. This might lead to small time delays when handling
  1054.      large hash tables.  This method does not free the memory allocated
  1055.      for the keys stored in the hash table. If the supplied key does
  1056.      not match any in the table, `FALSE' is returned, otherwise `TRUE'.
  1057.  
  1058. `bool delete_key_absolutely(CNKey *k);'
  1059.      Deletes the key from the actual hash table which matches the given
  1060.      key. After having deleted a key from the hash table, the whole
  1061.      table is rehashed. This method does free the memory allocated for
  1062.      the keys stored in the hash table. If the supplied key does not
  1063.      match any in the table, `FALSE' is returned, otherwise `TRUE'.
  1064.  
  1065.    The following example shows how to use a `CNHashStatic' object in
  1066. order to store and retrieve CNCL compatible objects.
  1067.  
  1068.      CNHashStatic tab(200);
  1069.      CNKeyString ks("Test", NIL);
  1070.      CNObject *obj = &ks;
  1071.      
  1072.      tab.store_key(new CNKeyString("Jabba", obj));
  1073.      tab.store_key(new CNKeyString("Dabba"));
  1074.      tab.store_key(new CNKeyString("Dooo"));
  1075.      
  1076.      if (tab.get_object(CNKeyString("Jabba")) != obj)
  1077.         cout << "strange behaviour\n";
  1078.      else
  1079.         cout << "found obj\n";
  1080.      
  1081.      tab.store_key(new CNKeyInt(10, obj)); // error, key of different type
  1082.      
  1083.      tab.reset_absolutely();
  1084.      
  1085.      tab.store_key(new CNKeyInt(10, obj)); // okay
  1086.  
  1087. 
  1088. File: cncl.info,  Node: CNHashDynamic,  Next: CNHashIterator,  Prev: CNHashStatic,  Up: Object Management
  1089.  
  1090. CNHashDynamic -- Hash Tables with Dynamic Capacity
  1091. ==================================================
  1092.  
  1093. SYNOPSIS
  1094. --------
  1095.  
  1096.    `#include <CNCL/HashDynamic.h>'
  1097.  
  1098. TYPE
  1099. ----
  1100.  
  1101.    `CN_HASHDYNAMIC'
  1102.  
  1103. * Menu:
  1104.  
  1105. BASE CLASSES
  1106. ------------
  1107. * CNHashTable::        Abstract Base Class for Hash Tables
  1108.  
  1109. DERIVED CLASSES
  1110. ---------------
  1111.  
  1112. RELATED CLASSES
  1113. ---------------
  1114. * CNHashStatic::    Hash Tables with Static Capacity
  1115. * CNHashIterator::      Sequential Iterator for Hash Tables
  1116. * CNKey::        Abstract Base Class for Object Management via Keys
  1117. * CNKeyString::        Object Management via String Keys
  1118. * CNKeyInt::        Object Management via Integer Keys
  1119. * CNManager::        Object Management Frontend
  1120.  
  1121. DESCRIPTION
  1122. -----------
  1123.  
  1124.    `CNHashDynamic' is a class which provides a hash table with dynamic
  1125. capacity for storing and retrieving CNCL compatible objects.
  1126.  
  1127.    Constructors:
  1128.  
  1129. `CNHashDynamic(unsigned long cap = DEFAULT_HASH_TABLE_CAPACITY);'
  1130. `CNHashDynamic(CNParam *param);'
  1131.      Initializes `CNHashDynamic'. The hash table's capacity is set to
  1132.      the value passed to HashDynamic. The capacity is dynamic, i.e. if
  1133.      the number of entries exceeds 3/4 of the hash table's capacity, it
  1134.      is enlarged to a proper value.
  1135.  
  1136.    Destructors:
  1137.  
  1138. `~CNHashDynamic();'
  1139.      Frees all internally allocated resources.
  1140.  
  1141.    `CNHashDynamic' provides the member functions required by CNCL and
  1142. `CNHashTable'.  Some member functions defined in `CNHashTable' and
  1143. implemented in `CNHashDynamic' demand further explanation:
  1144.  
  1145. `void store_key(CNKey *k);'
  1146.      Stores a key into the homogenous hash table.  Therefore, only keys
  1147.      of the same type may be stored into the same table. If you
  1148.      nevertheless try to store keys of different types into one table,
  1149.      it might be detected by the methods `get_key()' and
  1150.      `get_object()'. The capacity is dynamic, i.e. if the number of
  1151.      entries exceeds 3/4 of the hash table's capacity, it is enlarged
  1152.      to a proper value.
  1153.  
  1154. `bool delete_key(CNKey *k);'
  1155.      Deletes the key from the actual hash table which matches the given
  1156.      key. After having deleted a key from the hash table, the whole
  1157.      table is rehashed, i.e. the positions of all entries within the
  1158.      hash table are recalculated and all entries are stored in a new
  1159.      hash table. This might lead to small time delays when handling
  1160.      large hash tables.  This method does not free the memory allocated
  1161.      for the keys stored in the hash table. If the supplied key does
  1162.      not match any in the table, `FALSE' is returned, otherwise `TRUE'.
  1163.  
  1164. `bool delete_key_absolutely(CNKey *k);'
  1165.      Deletes the key from the actual hash table, which matches the given
  1166.      key. After having deleted a key from the hash table, the whole
  1167.      table is rehashed. This method does free the memory allocated for
  1168.      the keys stored in the hash table. If the supplied key does not
  1169.      match any in the table, `FALSE' is returned, otherwise `TRUE'.
  1170.  
  1171.    Refer to `CNHashStatic' for an example as to how to use a
  1172. `CNHashDynamic' object in order to store and retrieve CNCL compatible
  1173. objects.
  1174.  
  1175. 
  1176. File: cncl.info,  Node: CNHashIterator,  Next: CNManager,  Prev: CNHashDynamic,  Up: Object Management
  1177.  
  1178. CNHashIterator -- Sequential Iterator for Hash Tables
  1179. =====================================================
  1180.  
  1181. SYNOPSIS
  1182. --------
  1183.  
  1184.    `#include <CNCL/HashIterator.h>'
  1185.  
  1186. TYPE
  1187. ----
  1188.  
  1189.    `CN_HASHITERATOR'
  1190.  
  1191. * Menu:
  1192.  
  1193. BASE CLASSES
  1194. ------------
  1195. * CNObject::        Root of the CNCL Hierarchy
  1196.  
  1197. DERIVED CLASSES
  1198. ---------------
  1199.  
  1200. RELATED CLASSES
  1201. ---------------
  1202. * CNHashTable::        Abstract Base Class for Hash Tables
  1203. * CNHashDynamic::    Hash Tables with Dynamic Capacity
  1204. * CNHashStatic::    Hash Tables with Static Capacity
  1205. * CNKey::        Abstract Base Class for Object Management via Keys
  1206. * CNKeyString::        Object Management via String Keys
  1207. * CNKeyInt::        Object Management via Integer Keys
  1208. * CNManager::        Object Management Frontend
  1209.  
  1210. DESCRIPTION
  1211. -----------
  1212.  
  1213.    `CNHashIterator' is an iterator to sequentially traverse a
  1214. `CNHashTable' hash table.
  1215.  
  1216.    Constructors:
  1217.  
  1218. `CNHashIterator();'
  1219. `CNHashIterator(CNParam *param);'
  1220.      Initializes `CNHashIterator'.
  1221.  
  1222. `CNHashIterator(const CNHashTable *new_hash_table);'
  1223. `CNHashIterator(const CNHashTable &new_hash_table);'
  1224.      Initializes `CNHashIterator' with hash table `new_hash_table'. The
  1225.      iterator is reset to the first element of the hash table.
  1226.  
  1227.    In addition to the member functions required by CNCL,
  1228. `CNHashIterator' provides:
  1229.  
  1230. `void reset(const CNHashTable *new_hash_table);'
  1231. `void reset(const CNHashTable &new_hash_table);'
  1232. `void reset();'
  1233.      Resets the iterator to a new hash table `new_hash_table' and/or
  1234.      sets the iterator to the first element of the hash table.
  1235.  
  1236. `CNKey *key()'
  1237. `CNKey *get_key()'
  1238.      Gets the referenced key from the current iterator position. It
  1239.      returns the key or `NIL', if none is available.
  1240.  
  1241. `CNKey *first_key();'
  1242. `CNKey *first();'
  1243.      Sets the iterator to the first element of the hash table. It
  1244.      returns the referenced key or `NIL', if none is available.
  1245.  
  1246. `CNKey *last_key();'
  1247. `CNKey *last();'
  1248.      Sets the iterator to the last element of the hash table. It
  1249.      returns the referenced key or `NIL', if none is available.
  1250.  
  1251. `CNKey *next_key();'
  1252. `CNKey *next();'
  1253. `CNKey *operator ++();'
  1254. `CNKey *operator ++(int);'
  1255.      Moves the iterator to the next element of the hash table. It
  1256.      returns the current referenced key (the one BEFORE moving the
  1257.      iterator) or `NIL', if none is available.
  1258.  
  1259. `CNKey *prev_key();'
  1260. `CNKey *prev();'
  1261. `CNKey *operator --();'
  1262. `CNKey *operator --(int);'
  1263.      Moves the iterator to the previous element of the hash table. It
  1264.      returns the current referenced key (the one BEFORE moving the
  1265.      iterator) or `NIL', if none is available.
  1266.  
  1267. `CNObject *object()'
  1268. `CNObject *get_object()'
  1269.      Gets the object of the referenced key from the current iterator
  1270.      position. It returns the object or `NIL', if none is available.
  1271.  
  1272. `CNObject *first_object();'
  1273.      Sets the iterator to the first element of the hash table. It
  1274.      returns the object of the referenced key or `NIL', if none is
  1275.      available.
  1276.  
  1277. `CNObject *last_object();'
  1278.      Sets the iterator to the last element of the hash table. It
  1279.      returns the object of the referenced key or `NIL', if none is
  1280.      available.
  1281.  
  1282. `CNObject *next_object();'
  1283.      Moves the iterator to the next element of the hash table. It
  1284.      returns the object of the current referenced key (the one BEFORE
  1285.      moving the iterator) or `NIL', if none is available.
  1286.  
  1287. `CNObject *prev_object();'
  1288.      Moves the iterator to the previous element of the hash table. It
  1289.      returns the current referenced key (the one BEFORE moving the
  1290.      iterator) or `NIL', if none is available.
  1291.  
  1292.    The following examples show how to use a `CNHashIterator' object to
  1293. traverse an hash table:
  1294.  
  1295. Forward:
  1296.  
  1297.      CNHashDynamic hash_table;
  1298.      
  1299.      ...
  1300.      
  1301.      CNHashIterator trav(hash_table);
  1302.      CNKey *key;
  1303.      CNObject *obj;
  1304.      
  1305.      while(key = trav++)
  1306.      {
  1307.          // Do something with key ...
  1308.          obj = key->get_object();
  1309.      }
  1310.  
  1311. Alternate forward:
  1312.  
  1313.      for(trav.reset(hash_table); key = trav.key(); trav.next())
  1314.      {
  1315.          // ...
  1316.      }
  1317.  
  1318. Forward with objects:
  1319.  
  1320.      for(trav.first(); obj = trav.object(); trav.next_object())
  1321.      {
  1322.          // ...
  1323.      }
  1324.  
  1325. Backward:
  1326.  
  1327.      for(trav.last(); key = trav.key(); trav--)
  1328.      {
  1329.          // ...
  1330.      }
  1331.  
  1332. The only way to delete all entries of an hash table, that is guaranteed
  1333. to work with `CNHashIterator':
  1334.  
  1335.      for(trav.reset(hash_table); key = trav.key(); trav.reset())
  1336.      {
  1337.          // delete object associated with key
  1338.          delete key->get_object();
  1339.          // delete hash table entry and key
  1340.          hash_table->delete_key_absolutely(key);
  1341.      }
  1342.  
  1343. 
  1344. File: cncl.info,  Node: CNManager,  Next: CNPipe,  Prev: CNHashIterator,  Up: Object Management
  1345.  
  1346. CNManager - Object Management Frontend
  1347. ======================================
  1348.  
  1349. SYNOPSIS
  1350. --------
  1351.  
  1352.    `#include <CNCL/Manager.h>'
  1353.  
  1354. TYPE
  1355. ----
  1356.  
  1357.    `CN_MANAGER'
  1358.  
  1359. * Menu:
  1360.  
  1361. BASE CLASSES
  1362. ------------
  1363. * CNObject::        Root of the CNCL Hierarchy
  1364.  
  1365. DERIVED CLASSES
  1366. ---------------
  1367.  
  1368. None
  1369.  
  1370. RELATED CLASSES
  1371. ---------------
  1372. * CNHashTable::        Abstract Base Class for Hash Tables
  1373. * CNHashDynamic::    Hash Tables with Dynamic Capacity
  1374. * CNKey::        Abstract Base Class for Object Management via Keys
  1375. * CNKeyString::        Object Management via String Keys
  1376. * CNKeyInt::        Object Management via Integer Keys
  1377.  
  1378. DESCRIPTION
  1379. -----------
  1380.  
  1381.    `CNManager' is a class which provides facilities for storing and
  1382. retrieving CNCL compatible objects in a filesystem-like manner.
  1383. Objects of type `CN_MANAGER' can be compared with directories, whereas
  1384. all other CNCL compatible objects play the role of the files.
  1385. `CNManager' internally uses a dynamic hash table for managing the
  1386. objects.
  1387.  
  1388.    Constructors:
  1389.  
  1390. `CNManager(char *object_name = NIL);'
  1391. `CNManager(CNParam *param);'
  1392.      Initializes `CNManager'.
  1393.  
  1394.    Destructor:
  1395.  
  1396. `~CNManager();'
  1397.      Frees all internally allocated resources.
  1398.  
  1399.    In addition to the member functions required by CNCL, `CNManager'
  1400. provides:
  1401.  
  1402. `CNObject *new_object(char *object_name, CNClassDesc desc, CNParam *param = NIL);'
  1403.      `new_object()' is used to create a tree of objects similar to a
  1404.      filesystem's tree of directories and files. The class descriptor
  1405.      `desc' determines whether a directory (`CN_MANAGER') or a file
  1406.      (any other type) is to be created.  The `object_name' may consist
  1407.      of a pathname and/or a basename.  All directory-names and the
  1408.      basename must be separated by slashes ('/'). The pointer to the
  1409.      new created object is returned, if no error occurs, otherwise, if
  1410.      e. g. the specified pathname was incorrect, `NIL' is returned.
  1411.  
  1412. `bool delete_object(char *object_name);'
  1413.      Removes the specified object from the internal hashtable. The
  1414.      memory allocated for the object via `new_object()' is deleted, too.
  1415.      As described under `new_object()' you may pass a filesystem-like
  1416.      path to `delete_object()'. If the object is deleted succesfully,
  1417.      `TRUE' is returned, `FALSE' otherwise. If the object to be deleted
  1418.      is a 'directory' and if the 'directory' still contains valid
  1419.      'files', `delete_object()' fails. You must first delete all
  1420.      subentries before deleting the entry itself.
  1421.  
  1422. `CNObject *get_object(char *object_name) const;'
  1423.      Returns the object associated to the given pathname. If the
  1424.      specified object does not exist, `NIL' is returned.
  1425.  
  1426. `char *get_name();'
  1427.      Returns the basename of the respective object.
  1428.  
  1429. `bool is_empty() const;'
  1430.      Returns TRUE if no object is stored in the storing facilities of
  1431.      this class, FALSE otherwise.
  1432.  
  1433.    The following example shows how to use `CNManager' objects in order
  1434. to store and retrieve CNCL compatible objects.
  1435.  
  1436.      // this is the root of the example's object hierarchy
  1437.      CNManager root;
  1438.      // some 'directory' pointers
  1439.      CNManager *mobile, *base, *subbase;
  1440.      // some 'file' pointers
  1441.      CNHashDynamic *table1, *table2;
  1442.      
  1443.      // create a 'directory' in the root 'directory'
  1444.      mobile = (CNManager *)root.new_object("mobile", CN_MANAGER);
  1445.      if (mobile == NIL)
  1446.          ...
  1447.      // create another 'directory'
  1448.      base = (CNManager *)root.new_object("base", CN_MANAGER);
  1449.      if (base == NIL)
  1450.          ...
  1451.      
  1452.      // now create a 'file' (CNCL compatible object) in the
  1453.      // 'mobile' 'directory'
  1454.      table1 = (CNHashDynamic *)mobile->new_object("table1", CN_HASHDYNAMIC);
  1455.      if (table1 == NIL)
  1456.          ...
  1457.      
  1458.      // now create a 'subdirectory' of 'base' using an absolute path
  1459.      subbase = (CNManager *)root.new_object("/base/subbase", CN_MANAGER);
  1460.      if (subbase == NIL)
  1461.          ...
  1462.      
  1463.      // create a 'file' using a path relative to 'base'
  1464.      table2 = (CNHashDynamic *)base->new_object("subbase/table2", CN_HASHDYNAMIC);
  1465.      if (table2 == NIL);
  1466.          ...
  1467.      
  1468.      // now try to get an object
  1469.      if (base->get_object("subbase/table2") == table2)
  1470.          ...
  1471.      
  1472.      // try to delete 'subbase'
  1473.      if (!root.delete_object("/base/subbase"))    // error, dir not empty
  1474.          ...
  1475.      
  1476.      // first delete all subentries
  1477.      if (!root.delete_object("/base/subbase/table2"))
  1478.          ...
  1479.      
  1480.      // now delete subbase
  1481.      if (!base->delete_object("subbase"))    // okay
  1482.          ...
  1483.      
  1484.      ...
  1485.  
  1486. 
  1487. File: cncl.info,  Node: Misc,  Next: EZD Interface,  Prev: Unix,  Up: Top
  1488.  
  1489. Miscellaneous Classes
  1490. *********************
  1491.  
  1492.    The classes described in this chapter are provided by the CNCL class
  1493. library for miscellaneous purposes such as:
  1494. `common coordinates for the graphical interface to EZD'
  1495. `common string handling (as a CNObject)'
  1496. `common integer and double handling (as a CNObject)'
  1497. `support of named object management'
  1498. `integer2string and double2string conversion'
  1499. `reference counting'
  1500. * Menu:
  1501.  
  1502. * CNCoord::                     2-Dimensional Coordinates
  1503. * CNICoord::                    2-Dimensional Integer Coordinates
  1504. * CNString::                    Character String
  1505. * CNNamed::                     CNObject with Name
  1506. * CNIniFile::                   .ini-style config file
  1507. * CNFormInt::                   Integer as CNStrings
  1508. * CNFormFloat::                 Doubles as CNStrings
  1509. * CNInt::                       Integer derived from CNObject
  1510. * CNDouble::                    Double derived from CNObject
  1511. * CNGetOpt::                    Interface to GNU getopt()
  1512. * CNRef::                       Base class for classes with reference counting
  1513. * CNRefObj::                    CNObject with reference counting
  1514. * CNRefNamed::                    CNNamed with reference counting
  1515. * CNPtr::                    Intelligent pointer to CNRefObjs
  1516.  
  1517. 
  1518. File: cncl.info,  Node: CNCoord,  Next: CNICoord,  Prev: CNSelect,  Up: Misc
  1519.  
  1520. CNCoord -- 2-Dimensional Coordinates
  1521. ====================================
  1522.  
  1523. SYNOPSIS
  1524. --------
  1525.  
  1526.    `#include <CNCL/Coord.h>'
  1527.  
  1528. TYPE
  1529. ----
  1530.  
  1531.    `CN_COORD'
  1532.  
  1533. * Menu:
  1534.  
  1535. BASE CLASSES
  1536. ------------
  1537. * CNObject::        Root of the CNCL Hierarchy
  1538.  
  1539. DERIVED CLASSES
  1540. ---------------
  1541.  
  1542. RELATED CLASSES
  1543. ---------------
  1544. * CNICoord::        2-Dimensional Integer Coordinates
  1545.  
  1546. DESCRIPTION
  1547. -----------
  1548.  
  1549.    `CNCoord' is a data type for managing 2-dimensional coordinates. It
  1550. is typically used together with `CNICoord' for world coordinates and
  1551. pixel coordinates respectively.
  1552. A `CNCoord' has `double' x and y members which are public accessible.
  1553. `CNCoord's can be automatically converted to `CNICoord's and vice
  1554. versa. This is done by applying the conversion factor `CNCoord::scale'.
  1555.  
  1556.    Constructors:
  1557.  
  1558. `CNCoord();'
  1559. `CNCoord(CNParam *param);'
  1560. `CNCoord(double vx, double vy);'
  1561. `CNCoord(const CNICoord &v);'
  1562. `CNCoord(const CNCoord &v);'
  1563.      Initializes the coordinates object and optionally sets x and y
  1564.      components.
  1565.  
  1566.    Public accessible members:
  1567.  
  1568. `double x;'
  1569. `double y;'
  1570.      The x and y components of `CNCoord'.
  1571.  
  1572.    In addition to the member functions required by CNCL, `CNCoord'
  1573. provides:
  1574.  
  1575. `CNCoord &operator = (const CNCoord &v);'
  1576. `CNCoord &operator += (const CNCoord &v);'
  1577. `CNCoord &operator -= (const CNCoord &v);'
  1578.      Defines the operators `=', `+=' and `-=' for coordinates by
  1579.      applying the standard C/C++ operators to the x and y components.
  1580.  
  1581.    The following static member functions are provided to manipulate the
  1582. conversion scale setting:
  1583.  
  1584. `static double CNCoord::get_scale();'
  1585. `static double CNCoord::set_scale(double new_scale);'
  1586.      Gets/sets the scale setting.
  1587.  
  1588.    Global operators:
  1589.  
  1590. `CNCoord operator + (const CNCoord &a, const CNCoord &b);'
  1591. `CNCoord operator - (const CNCoord &a, const CNCoord &b);'
  1592.      Adds/substracts coordinates by adding/subtracting the x and y
  1593.      components.
  1594.  
  1595. 
  1596. File: cncl.info,  Node: CNICoord,  Next: CNString,  Prev: CNCoord,  Up: Misc
  1597.  
  1598. CNICoord -- 2-Dimensional Integer Coordinates
  1599. =============================================
  1600.  
  1601. SYNOPSIS
  1602. --------
  1603.  
  1604.    `#include <CNCL/ICoord.h>'
  1605.  
  1606. TYPE
  1607. ----
  1608.  
  1609.    `CN_ICOORD'
  1610.  
  1611. * Menu:
  1612.  
  1613. BASE CLASSES
  1614. ------------
  1615. * CNObject::        Root of the CNCL Hierarchy
  1616.  
  1617. DERIVED CLASSES
  1618. ---------------
  1619.  
  1620. RELATED CLASSES
  1621. ---------------
  1622. * CNCoord::        2-Dimensional Coordinates
  1623.  
  1624. DESCRIPTION
  1625. -----------
  1626.  
  1627.    `CNICoord' is a data type for managing 2-dimensional integer
  1628. coordinates. It is typically used with `CNCoord' for pixel coordinates
  1629. and world coordinates respectively.
  1630. A `CNICoord' has `int' x and y members which are public accessible.
  1631. `CNICoord's can be automatically converted to `CNCoord's and vice
  1632. versa. This is done by applying the conversion factor `CNCoord::scale'.
  1633.  
  1634.    Constructors:
  1635.  
  1636. `CNICoord();'
  1637. `CNICoord(CNParam *param);'
  1638. `CNICoord(int vx, int vy);'
  1639. `CNICoord(const CNCoord &v);'
  1640. `CNICoord(const CNICoord &v);'
  1641.      Initializes the integer coordinates object and optionally sets x
  1642.      and y components.
  1643.  
  1644.    Public accessible members:
  1645.  
  1646. `int x;'
  1647. `int y;'
  1648.      The x and y components of `CNICoord'.
  1649.  
  1650.    In addition to the member functions required by CNCL, `CNICoord'
  1651. provides:
  1652.  
  1653. `CNICoord &operator += (const CNICoord &v);'
  1654. `CNICoord &operator -= (const CNICoord &v);'
  1655.      Defines the operators `+=' and `-=' for integer coordinates,
  1656.      applying the standard C/C++ operators to the x and y components.
  1657.  
  1658.    The following static member functions are provided to manipulate the
  1659. conversion scale setting:
  1660.  
  1661. `static double CNICoord::get_scale();'
  1662. `static double CNICoord::set_scale(double new_scale);'
  1663.      Gets/sets the scale setting.
  1664.  
  1665.    Global operators:
  1666.  
  1667. `CNICoord operator + (const CNICoord &a, const CNICoord &b);'
  1668. `CNICoord operator - (const CNICoord &a, const CNICoord &b);'
  1669.      Adds/substracts integer coordinates by adding/subtracting the x
  1670.      and y components.
  1671.  
  1672.